home *** CD-ROM | disk | FTP | other *** search
/ MacHack 2000 / MacHack 2000.toast / pc / The Hacks / Dialing Addresses / Src / AddressDB.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-06-23  |  11.5 KB  |  347 lines

  1. /*******************************************************************
  2.  Copyright © 1995 - 1998, 3Com Corporation or its subsidiaries ("3Com").  
  3.  All rights reserved.
  4.    
  5.  This software may be copied and used solely for developing products for 
  6.  the Palm Computing platform and for archival and backup purposes.  Except 
  7.  for the foregoing, no part of this software may be reproduced or transmitted 
  8.  in any form or by any means or used to make any derivative work (such as 
  9.  translation, transformation or adaptation) without express written consent 
  10.  from 3Com.
  11.  
  12.  3Com reserves the right to revise this software and to make changes in content 
  13.  from time to time without obligation on the part of 3Com to provide notification 
  14.  of such revision or changes.  
  15.  3COM MAKES NO REPRESENTATIONS OR WARRANTIES THAT THE SOFTWARE IS FREE OF ERRORS 
  16.  OR THAT THE SOFTWARE IS SUITABLE FOR YOUR USE.  THE SOFTWARE IS PROVIDED ON AN 
  17.  "AS IS" BASIS.  3COM MAKES NO WARRANTIES, TERMS OR CONDITIONS, EXPRESS OR IMPLIED, 
  18.  EITHER IN FACT OR BY OPERATION OF LAW, STATUTORY OR OTHERWISE, INCLUDING WARRANTIES, 
  19.  TERMS, OR CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND 
  20.  SATISFACTORY QUALITY.
  21.  
  22.  TO THE FULL EXTENT ALLOWED BY LAW, 3COM ALSO EXCLUDES FOR ITSELF AND ITS SUPPLIERS 
  23.  ANY LIABILITY, WHETHER BASED IN CONTRACT OR TORT (INCLUDING NEGLIGENCE), FOR 
  24.  DIRECT, INCIDENTAL, CONSEQUENTIAL, INDIRECT, SPECIAL, OR PUNITIVE DAMAGES OF 
  25.  ANY KIND, OR FOR LOSS OF REVENUE OR PROFITS, LOSS OF BUSINESS, LOSS OF INFORMATION 
  26.  OR DATA, OR OTHER FINANCIAL LOSS ARISING OUT OF OR IN CONNECTION WITH THIS SOFTWARE, 
  27.  EVEN IF 3COM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  28.  
  29.  3Com, HotSync, Palm Computing, and Graffiti are registered trademarks, and 
  30.  Palm III and Palm OS are trademarks of 3Com Corporation or its subsidiaries.
  31.  
  32.  IF THIS SOFTWARE IS PROVIDED ON A COMPACT DISK, THE OTHER SOFTWARE AND 
  33.  DOCUMENTATION ON THE COMPACT DISK ARE SUBJECT TO THE LICENSE AGREEMENT 
  34.  ACCOMPANYING THE COMPACT DISK.
  35.  
  36.  *-------------------------------------------------------------------
  37.  * FileName:
  38.  *        AddressMgr.h
  39.  *
  40.  * Description:
  41.  *        Header for the Address Manager
  42.  *
  43.  * History:
  44.  *       1/3/95  rsf - Created
  45.  *
  46.  *******************************************************************/
  47.  
  48. #ifndef __ADDRESSDB_H__
  49. #define __ADDRESSDB_H__
  50.  
  51. #include "AppLaunchCmd.h"
  52.  
  53.  
  54. #define LocalizedAppInfoStr            1000
  55.  
  56. #define addrLabelLength        16
  57. #define addrNumFields        19
  58.  
  59.  
  60. typedef union {
  61.     struct {
  62.         unsigned reserved        :13;
  63.         unsigned note        :1;    // set if record contains a note handle
  64.         unsigned custom4     :1;    // set if record contains a custom4
  65.         unsigned custom3     :1;    // set if record contains a custom3
  66.         unsigned custom2     :1;    // set if record contains a custom2
  67.         unsigned custom1     :1;    // set if record contains a custom1
  68.         unsigned title       :1;    // set if record contains a title
  69.         unsigned country        :1;    // set if record contains a birthday
  70.         unsigned zipCode        :1;    // set if record contains a birthday
  71.         unsigned state            :1;    // set if record contains a birthday
  72.         unsigned city           :1;    // set if record contains a birthday
  73.         unsigned address     :1;    // set if record contains a address
  74.         unsigned phone5      :1;    // set if record contains a phone5
  75.         unsigned phone4      :1;    // set if record contains a phone4
  76.         unsigned phone3      :1;    // set if record contains a phone3
  77.         unsigned phone2      :1;    // set if record contains a phone2
  78.         unsigned phone1      :1;    // set if record contains a phone1
  79.         unsigned company     :1;    // set if record contains a company
  80.         unsigned firstName   :1;    // set if record contains a firstName
  81.         unsigned name        :1;    // set if record contains a name (bit 0)
  82.         
  83.     } bits;
  84.     ULong allBits;
  85. } AddrDBRecordFlags;
  86.  
  87. typedef union {
  88.     struct {
  89.         unsigned reserved        :10;
  90.         unsigned phone8      :1;    // set if phone8 label is dirty
  91.         unsigned phone7      :1;    // set if phone7 label is dirty
  92.         unsigned phone6      :1;    // set if phone6 label is dirty
  93.         unsigned note        :1;    // set if note label is dirty
  94.         unsigned custom4     :1;    // set if custom4 label is dirty
  95.         unsigned custom3     :1;    // set if custom3 label is dirty
  96.         unsigned custom2     :1;    // set if custom2 label is dirty
  97.         unsigned custom1     :1;    // set if custom1 label is dirty
  98.         unsigned title       :1;    // set if title label is dirty
  99.         unsigned country        :1;    // set if country label is dirty
  100.         unsigned zipCode        :1;    // set if zipCode label is dirty
  101.         unsigned state            :1;    // set if state label is dirty
  102.         unsigned city           :1;    // set if city label is dirty
  103.         unsigned address     :1;    // set if address label is dirty
  104.         unsigned phone5      :1;    // set if phone5 label is dirty
  105.         unsigned phone4      :1;    // set if phone4 label is dirty
  106.         unsigned phone3      :1;    // set if phone3 label is dirty
  107.         unsigned phone2      :1;    // set if phone2 label is dirty
  108.         unsigned phone1      :1;    // set if phone1 label is dirty
  109.         unsigned company     :1;    // set if company label is dirty
  110.         unsigned firstName   :1;    // set if firstName label is dirty
  111.         unsigned name        :1;    // set if name label is dirty (bit 0)
  112.         
  113.     } bits;
  114.     ULong allBits;
  115. } AddrDBFieldLabelsDirtyFlags;
  116.  
  117. /*
  118.  
  119. #define nameFlag            ((ULong) 1 << name)
  120. #define firstNameFlag    ((ULong) 1 << firstName)
  121. #define companyFlag        ((ULong) 1 << company)
  122. #define phone1Flag        ((ULong) 1 << phone1)
  123. #define phone2Flag        ((ULong) 1 << phone2)
  124. #define phone3Flag        ((ULong) 1 << phone3)
  125. #define phone4Flag        ((ULong) 1 << phone4)
  126. #define phone5Flag        ((ULong) 1 << phone5)
  127. #define addressFlag        ((ULong) 1 << address)
  128. #define cityFlag            ((ULong) 1 << city)
  129. #define stateFlag            ((ULong) 1 << state)
  130. #define zipCodeFlag        ((ULong) 1 << zipCode)
  131. #define countryFlag        ((ULong) 1 << country)
  132. #define titleFlag            ((ULong) 1 << title)
  133. #define custom1Flag        ((ULong) 1 << custom1)
  134. #define custom2Flag        ((ULong) 1 << custom2)
  135. #define custom3Flag        ((ULong) 1 << custom3)
  136. #define custom4Flag        ((ULong) 1 << custom4)
  137. #define noteFlag            ((ULong) 1 << note)
  138.  
  139. typedef char AddrDBRecordFlags[3];
  140. */
  141.  
  142.  
  143. typedef struct {
  144.     unsigned reserved:7;
  145.     unsigned sortByCompany    :1;
  146. } AddrDBMisc;
  147.  
  148. typedef enum {
  149.     name,
  150.     firstName,
  151.     company,
  152.     phone1,
  153.     phone2,
  154.     phone3,
  155.     phone4,
  156.     phone5,
  157.     address,
  158.     city,
  159.     state,
  160.     zipCode,
  161.     country,
  162.     title,
  163.     custom1,
  164.     custom2,
  165.     custom3,
  166.     custom4,
  167.     note,            // This field is assumed to be < 4K 
  168.     addressFieldsCount
  169. } AddressFields;
  170.  
  171.  
  172. // This structure is only for the exchange of address records.
  173. typedef union {
  174.     struct {
  175.         unsigned reserved        :8;
  176.         
  177.         // Typically only one of these are set
  178.         unsigned email            :1;    // set if data is an email address
  179.         unsigned fax            :1;    // set if data is a fax
  180.         unsigned pager            :1;    // set if data is a pager
  181.         unsigned voice            :1;    // set if data is a phone
  182.         
  183.         unsigned mobile        :1;    // set if data is a mobile phone
  184.         
  185.         // These are set in addition to other flags.
  186.         unsigned work            :1;    // set if phone is at work
  187.         unsigned home            :1;    // set if phone is at home
  188.         
  189.         // Set if this number is preferred over others.  May be preferred
  190.         // over all others.  May be preferred over other emails.  One 
  191.         // preferred number should be listed next to the person's name.
  192.         unsigned preferred   :1;    // set if this phone is preferred (bit 0)
  193.     } bits;
  194.     ULong allBits;
  195. } AddrDBPhoneFlags;
  196.  
  197. typedef enum {
  198.     workLabel,
  199.     homeLabel,
  200.     faxLabel,
  201.     otherLabel,
  202.     emailLabel,
  203.     mainLabel,
  204.     pagerLabel,
  205.     mobileLabel
  206. } AddressPhoneLabels;
  207.  
  208.  
  209. #define noRecord 0xffff
  210.  
  211. #define firstAddressField    name
  212. #define firstPhoneField        phone1
  213. #define lastPhoneField        phone5
  214. #define numPhoneLabels        8
  215. #define numPhoneFields        (lastPhoneField - firstPhoneField + 1)
  216. #define numPhoneLabelsStoredFirst    numPhoneFields
  217. #define numPhoneLabelsStoredSecond    (numPhoneLabels - numPhoneLabelsStoredFirst)
  218.  
  219. #define firstRenameableLabel    custom1
  220. #define lastRenameableLabel    custom4
  221. #define lastLabel                    (addressFieldsCount + numPhoneLabelsStoredSecond)
  222.  
  223. #define IsPhoneLookupField(p)    (addrLookupWork <= (p) && (p) <= addrLookupMobile)
  224.  
  225.  
  226. typedef union {
  227.     struct {
  228.         unsigned reserved:8;
  229.         unsigned displayPhoneForList:4;    // The phone displayed for the list view 0 - 4
  230.         unsigned phone5:4;                // Which phone (home, work, car, ...)
  231.         unsigned phone4:4;
  232.         unsigned phone3:4;
  233.         unsigned phone2:4;
  234.         unsigned phone1:4;
  235.     } phones;
  236.     ULong phoneBits;
  237. } AddrOptionsType;
  238.  
  239.  
  240.  
  241. // AddrDBRecord.
  242. //
  243. // This is the unpacked record form as used by the app.  Pointers are 
  244. // either NULL or point to strings elsewhere on the card.  All strings 
  245. // are null character terminated.
  246.  
  247. typedef struct {
  248.     AddrOptionsType    options;        // Display by company or by name
  249.     CharPtr            fields[addressFieldsCount];
  250. } AddrDBRecordType;
  251.  
  252. typedef AddrDBRecordType * AddrDBRecordPtr;
  253.  
  254.  
  255. // AddrPackedDBRecord
  256. //
  257. // Immediately following this structure are 0 - 15 data strings.  Each string
  258. // is present ONLY if the appropriate flag is set in the AddrDBRecordFlags.
  259. // Each string is in the same order as in AddrDBRecordFlags.
  260.  
  261. // typedef {
  262. //        AddrOptionsType     options;        // Display by company or by name
  263. //        AddrDBRecordFlags   flags;
  264. //        unsigned char        companyFieldOffset;
  265. //        char                firstField;
  266. // } AddrPackedDBRecord;
  267.  
  268.  
  269. // The labels for phone fields are stored specially.  Each phone field
  270. // can use one of eight labels.  Part of those eight labels are stored
  271. // where the phone field labels are.  The remainder (phoneLabelsStoredAtEnd)
  272. // are stored after the labels for all the fields.
  273.  
  274. typedef char addressLabel[addrLabelLength];
  275.  
  276.  
  277. typedef struct {
  278.     UInt                    renamedCategories;    // bitfield of categories with a different name
  279.     char                     categoryLabels[dmRecNumCategories][dmCategoryLength];
  280.     Byte                     categoryUniqIDs[dmRecNumCategories];
  281.     Byte                    lastUniqID;    // Uniq IDs generated by the device are between
  282.                                             // 0 - 127.  Those from the PC are 128 - 255.
  283.     Byte                    reserved1;    // from the compiler word aligning things
  284.     Word                    reserved2;
  285.     AddrDBFieldLabelsDirtyFlags dirtyFieldLabels;
  286.     addressLabel         fieldLabels[addrNumFields + numPhoneLabelsStoredSecond];
  287.     CountryType         country;        // Country the database (labels) is formatted for
  288.     AddrDBMisc            misc;
  289. } AddrAppInfoType;
  290.  
  291. typedef AddrAppInfoType * AddrAppInfoPtr;
  292.  
  293.  
  294. #define GetPhoneLabel(r, p)    (((r)->options.phoneBits >> (((p) - firstPhoneField) << 2)) & 0xF)
  295.  
  296. #define SetPhoneLabel(r, p, pl)    ((r)->options.phoneBits = \
  297.                                             ((r)->options.phoneBits & ~((DWord) 0x0000000F << (((p) - firstPhoneField) << 2))) | \
  298.                                             ((DWord) pl << (((p) - firstPhoneField) << 2)))
  299.  
  300.  
  301. #ifdef __cplusplus
  302. extern "C" {
  303. #endif
  304.  
  305.  
  306. Err                AddrGetRecord(DmOpenRef dbP, UInt index, AddrDBRecordPtr recordP, 
  307.                         Handle *recordH);
  308.     
  309. Err                 AddrNewRecord(DmOpenRef dbP, AddrDBRecordPtr r, UInt *index);
  310.  
  311. Err                 AddrChangeRecord(DmOpenRef dbP, UInt *index, AddrDBRecordPtr r, 
  312.                         AddrDBRecordFlags changedFields);
  313.  
  314. Err                 AddrChangeSortOrder(DmOpenRef dbP, Boolean sortByCompany);
  315.  
  316. AddrAppInfoPtr    AddrAppInfoGetPtr(DmOpenRef dbP);
  317.  
  318. Err                 AddrAppInfoInit(DmOpenRef dbP);
  319.  
  320. void                 AddrChangeCountry(AddrAppInfoPtr appInfoP);
  321.  
  322. void                 AddrSetFieldLabel(DmOpenRef dbP, UInt fieldNum, CharPtr fieldLabel);
  323.  
  324. Boolean             AddrLookupString(DmOpenRef dbP, CharPtr key, 
  325.                         Boolean sortByCompany, UInt category, UIntPtr recordP, 
  326.                         Boolean *completeMatch);
  327.  
  328. Boolean            AddrLookupSeekRecord (DmOpenRef dbP, UIntPtr indexP, 
  329.                         UIntPtr phoneP, Int offset, Int direction, 
  330.                         AddressLookupFields field1, AddressLookupFields field2, 
  331.                         AddressFields lookupFieldMap[]);
  332.  
  333. Boolean            AddrLookupLookupString(DmOpenRef dbP, CharPtr key, 
  334.                         Boolean sortByCompany, AddressLookupFields field1, 
  335.                         AddressLookupFields field2, UIntPtr recordP, UIntPtr phoneP, 
  336.                         AddressFields lookupFieldMap[], 
  337.                         Boolean *completeMatch, Boolean *uniqueMatch);
  338.  
  339. Boolean             RecordContainsData (AddrDBRecordPtr recordP);
  340.  
  341. #ifdef __cplusplus
  342. }
  343. #endif
  344.  
  345.  
  346. #endif
  347.